Wintrace - Main Display

Click on any item for information:


Caption

Double Clicking on the caption bar will cause an abridged version of the main display to be shown. This display will consist of the GDI,USER, SYSTEM percentage free resources plus the amount of free memory. Double Clicking on this reduced display will display a pop-up menu from which you can choose the Always Top, Auto Update and Restore Main Display options


Module List

This window displays a list of all the modules currently loaded. The window displays the name of the modules; this is not necessarily the same as the file name for the module. Modules shown in lowercase are modules that have a usage count of zero but are still loaded. This window will be updated as modules as loaded or unloaded by the system.

This display uses a multi-selection listbox. Menu items such as delete will operate on all the selected items, others, such as detail, will only operate on the first selected item.

Double clicking on an item displays the following detail window :

The menu Options item has the following :

Detail.

This opens the detail window, shown above, for the currently selected item.

Delete.

This option will delete the selected items from memory. It does this by reducing the usage count to zero.

Refresh.

This option will rebuild the display.

Always Top.

This option will keep the module list window on top.


Load Path
The full path, including the file name, that this module was loaded from.


Usage
The usage count for this module. This number typically represents the difference between calls to LoadLibrary and FreeLibrary.


Handle
This is the Module Handle, displayed in hexadecimal.


Date
This is the Last Modification Date as recorded by the Operating System.


Time
This is the Last Modification Time as recorded by the Operating System.


Size
The size of the File in Bytes.


Version
This button, if enabled, will open up the version dialog box.


Resource
This button will open the module resource window.


Delete
This button will call FreeLibrary repeatedly until the Usage count reaches zero. At that time Windows will remove the Module from Memory.


The Toolbar

The toolbar has the following buttons :

-	Activates the Module Window

-	Activates the Trace Window

-	Activates the Windows Window

-	Activates the Task Window

-	Activates the Debug Window

-	Displays memory usage of the 1st Meg


Main Window Module List

This list shows all the modules loaded at the time wintrace was started. The elements shown in the list are :

Module Name

Full Path of where the module was loaded from

Usage count for the module

Version number.

This list will be updated to reflect modules being loaded and unloaded by the system.

This list can be refreshed by selecting either Refresh from the Options menu item, or by utilizing the Auto Update selection under the Options menu item. The Auto Update selection will open a dialog box where you can specify, in seconds, how often the list should be refreshed.

A list that includes file size, Date last modified and Time last modified can be built by selecting Detailed Display from the Options menu item.

Double Clicking on any entry will popup a menu with the following additional options :

Delete

Selecting this option will remove the hilighted module from memory.

Resources.

Selecting this option will display a dialog showing Local and Global memory usage for the hilighted module.

Version

Selecting this option will display detailed version information, if it has any, for the hilighted module.

Additional Information

Selecting this option will display additional information about the hilighted module including, Functions that it exports and Functions that it imports.

Load

Selecting this option will display a File Open Dialog where you can specify the path of a Module that Wintrace will load into memory.


Main Window Resources

The first two text boxes show the amount of free memory you have left and the size of the largest block, This figure includes virtual memory defined via a swap file.

The next three numbers displayed are the percentage of free System resources, the percentage of free User resources and the percentage of free GDI Resources.

These figues can be updated by selecting Refresh from the Options menu item.


Task List

This window displays a list of the currently executing tasks. This list includes all tasks, even those that do not have windows associated with them. While this window is open it will be updated as tasks start and finish.

The menu has the following options.

File.

Exit.

Closes the Task List window.

Options.

Terminate

This option will Terminate the selected Task. Wintrace will decrement the Usage Count of any DLLs that it knows this task has loaded. It will only know this information if Wintrace was active when the task started.

The task is terminated by a call to the TOOLHELP TerminateApp( ) API.

Wintrace uses the NotifyRegister NFYSTARTDLL message to keep track of which DLLs this task loaded.

NOTE.

If this Task Calls LoadLibrary etc for a DLL that is already loaded then Wintrace will not decrease the usage count when you terminate the Task.

Details

This Selection displays the following dialog:

Always Top

This option keeps the task list window visible at all times.

Double Clicking on an entry activates the details dialog.


Parent
The name of the task that started this task.


Task
The hexadecimal value of the task handle.


Current Module
The path and name of the currently executing Module for this task.


Window Caption
The Caption of the active window for the task.


Loaded DLLs
The full path and file name of any DLLs that were loaded into Memory by this task. If the same entry occurs multiple times it signifies that the task has  freed and reloaded the DLL.


Memory
This button will open up the resource dialogwhere a high level overview of memory usage for this task will be shown.


Resources
Resources.

Opens a Dialog where resources embeddedwithin the .EXE can be examined.


Below 1MB

Displays the number of bytes of memory used by this task that have an address below 1MB. Windows™ Needs memory from this area to create new tasks.

See  First Meg of Memory for more details


Trace Window

This is the window where all trace activity is displayed. All output from the NotifyRegister( )  Function is displayed here.

API Trace requests made in the Debug Window and, optionally Window messages, are also displayed here.

Entrys are displayed in the following format :

HH:MM:SS 	Type	 Task	 Message

HH:MM:SS.

This is the time the trace entry was processed by Wintrace.

Type.

This is only relevant for  NotifyRegister( ) Entrys. The values and their meanings are:

StrTsk:

This message is displayed when a new task is started. Wintrace displays the name of the task.

EndTsk:

This message is displayed when a task is ending. Wintrace displays the task name and the exit code. This entry is almost immediately follows by a DelMod  for a module with the same name as the task.

StrDLL:

This message is displayed when a DLL is about to be loaded for the first time. Wintrace displays the name of the module being loaded.

DelMod:

This message is display when a Module (DLL) is about to be removed  from memory. This indicates that the usage count has reached zero.

ErrRIP:

Generated by a call to FatalExit( ). Wintrace displays the CS:IP plus SS:BP and the exit code.

PrmMsg:

Displays either a Parameter Warning or a Parameter Error. It also displays the name of module in which the API that was called resides, the value of the parameter and the error text.

LogMsg:

The Kernel sends this message when it detects a parameter error. Wintrace displays whether this is a warning or an error, the value of the parameter causing the problem and the error text.

OutStr:

This message is displayed in response to a call to the OutputDebugString( )  API Wintrace concatenates the strings passed to OutputDebugString( ) until a CR/LF is encountered. It then displays the resulting string.

If, after a 1,000 bytes, a CR/LF has not been sent Wintrace will force a line break.

Internally Wintrace maintains a 12K circular buffer for storing trace messages. If your applications calls OutputDebugString( ) many times without any intervening calls to GetMessage( ) then there is a chance that this buffer may fill.

If this occurs try placing a call to Yield( ) at strategic points in your application.

SeeTrace Menu for the various filter options etc.


Trace

The trace output is displayed in this window. The window is actually a scrolling Listbox with both horizontal and vertical scroll bars.


NotifyRegister( )

See the description of NotifyRegister in the SDK.


OutputDebugString( )

See the description of the OutputDebugString Function in the SDK.


Trace Menu

File.

Exit.

Closes the Debug Window and all Child MDI windows. Any tracing, including API, is deactivated.

Window

Tile.

Tiles all MDI windows.

Cascade

Cascades all MDI windows.

Arrange Icons

Lines up all Iconized windows.

Window name

Activates the window with the specified caption, if the window is currently minimized it is restored.

Edit

Cut

Removes the selected entries from the trace window and places them in the clipboard.

Copy

Copies the selected entries from the trace window to the clipboard.

Options

Clear Window

Clears the trace window.

DOS Trace (INT 21H)

Traces any INT 21H executed by an application running in the system VM.

Font

Opens up a font Select window where you may specify the font and size you wish the Trace output to be displayed in.

Pause

Prevents the trace display from being updated. Any messages that were sent during this time are lost.

Resume

Resumes updating of the trace display.

Output

Window.

Specifies that trace output should be displayed in the trace window.

File

Specifies that trace output should be directed to a file. Wintrace will prompt you for the name and path of the file to write the entries to.

Both

Specifies that trace output should be both displayed and written to a file. Wintrace will prompt you for the name and path of the file to write the entries to.

Filters

Opens a dialog box where you may specify which TOOLHELP notification messages are to be displayed. See the NotifyRegister( ) API in the SDK for more information.


Main Window Menu

The main Window has the following Menu Items:

File.

Exit.

View

Tasks.	Open the Task display dialog

Modules	Open the Module List dialog.

Resources	Open the resource dialog

Trace	Open the Trace Window

Windows	Open the Windows Dialog.


Exit

Closes all open windows and Exits Wintrace. F3 can be used as an accelerator.


Windows Window

This Window displays a list, by owning Task, of all the parent windows. It displays the Class name and the Window Handle (HWND). The initail list shows the task currently running on your system. Double clicking on an entry expands or compresses the list of parent windows for that task.

The Menu Options are:

File:

Exit.

Close this Window

Options.

Messages.

Opens a Message Window for the selected entry.

Detail.

Opens a Detail window for the selected entry.

Refresh.

Refreshes the display

Auto Update.

Opens a dialog box where you can specify, in seconds, how often the display should be automatically refreshed.

Select.

Opens a Selection dialog where you can click on the window whoses messages you wish to trace.

Double clicking on a window  entry opens the Detail window.


Debug Window

This dialog, activated by clicking the Debug button ( [image]) on the main display,  is where you select the various debugging options of WINTRACE. From this dialog you can select APIs that you are interested in. You can then specify  whether you wish to trace calls to those APIs with a display of the input parameters and the API returns; or maintain a Count and a response time of calls to the APIs.

As a help in debugging your own applications you can also monitor an applications resource usage, perform parameter validation, with instant notification on errors, and check for both local and global memory overwrites. Each option is described in more detail below:

Trace:

Whenever the selected APIs are called by the selected tasks/modules an entry will be written to the trace window. The entry displayed will be similar to the following.

21:58:52 OutStr MPLAYER:	Module KRNL386.EXE function LOCALALLOC called by MPLAYER IN :  0020  01D2  OUT  5F40

This entry indicates that task MPLAYER invoked a function called LocalAlloc which resides in KRNL386.EXE. The modules making the call was MPLAYER. The parameters passed to LocalAlloc were 0x0020 and 0x01D2 the return was the HLOCAL HANDLE of 0x5F40.

Time:

A Count of the number of times the selected APIs have been called by the selected Tasks/Modules will be kept. Along with this count WINTRACE will also keep the Average time for the function to execute , the maximum time the function has taken to execute and the parameters supplied to the function for the maximum time. Output is displayed by selecting Timing Results from the Main Menu.

The results appear as follows:

WINEXEC	4	5	9	C:\WINDOWS\WRITE.EXE  0001

This shows that WINEXEC has been called 4 times since this option was selected. It has taken, on average 0.5 seconds to execute with a maximum time of 0.9 seconds when WRITE.EXE 0001 were passed as parameters.

WINTRACE only resolves to 1 tenth of a second.

Monitor Resource Usage.

This option allows you to track what resources a task or module is using and where they are being allocated. It uses entries in the WINTRACE.API file to determine which API calls allocate a resource. All output is displayed on the resource output window.


API Functions

This is the list of  DLLs and the Functions in those DLLs that are available for Debugging. This list is built from the entries in the file  WINTRACE.API.


API Options

 Trace :  Trace calls to the selected APIs. WINTRACE will display the parameters upon entry to the call and the result  upon return from the API. The information is displayed on the Trace Window.

Time :     Keeps a count of the number of times the selected APIs have been invoked plus the maximum and average response time. The information is displayed on the Timings window.

Break :   Not yet implemented.


Additional Options

Monitor Resource Usage:	Keeps track of any selected APIs that allocate or free resources. APIs that allocate or free resources are specified in the WINTRACE.INI file. Resource information is displayed in the resource Window.

Check for Memory Overwrites:	Checks both Local and Global Memory blocks for overwrites. If any are detected the exception window is displayed.

Parameter Validation:	Checks that the parameters passed to the selected APIs are valid. If not the exception windowis displayed.


Reset

Resets all break points written and  stops all debug activity.


Add

Writes any required break points and activates the selected options for the selected APIs. Opens the Debug Output Window  if required.


Done

Closes this dialog.


Tasks

A list of the currently executing tasks. Select the tasks you wish to monitor.


Modules

A list of the all the currently loaded modules. Select the modules you wish to monitor.


IfLoaded

A list of Tasks/Modules you want to monitor if they start or are loaded. This list is specified in  WINTRACE.INI  The names here are the names of tha actual Tasks or the internal name of the Module. They are not the file name as it exists on Disk.


Mark Imports

For each selected entry  in either the module list or the task list  it selects the entries in the API Function List that this module imports.
For each selected entry in the Ifloaded list it prompts for the Location of the corresponding DLL or .EXE and then selects APIs that it imports.

This option will not select APIs that are invoked via a call to GetProcAddress( ).


Compress\Expand

This button will either Expand the list to show all the functions in each module or compress it.


Memory Usage Window

This dialog is displayed for both Tasks and Modules. It displays a high level picture of a Task or Modules memory usage. Clicking on either of the detail buttons will open a window giving a detailed breakdown of how the memory is allocated.

As you would expect Tasks do not have Local Memory.

This window can be opened from the task detail window or the module detail window.


Global Handles

Shows a count of the number of global handles currently owned by this Task/Module


Largest block

Shows the size of the largest block of Global/Local memory currently allocated by this Task/Module


Smallest Block

Shows the size of the smallest block of Global/Local memory currently allocated by this Task/Module


Total

Shows the total number of bytes of Global/Local memory currently allocated by this Task/Module


Global Detail

Displays a detailed breakdown of the global memory owned by this Task/Module.


Local Detail

Displays a detailed breakdown of the local memory allocated by this Task/Module.


Local Handles

Displays a count of the number of local handles allocated by this module.


    Window Detail

The following is displayed by either selecting Detail from the Windows Window or by double clicking on an entry in that window.


Visible

Yes if the parent window is visible, No if it is hidden.


Enabled

Yes if the parent window is enabled, No if it is disbaled.


Menu

The value of the parent windows menu, if it has one.


Caption

The text of the parent windows Caption, if it has one.


Children

A list of all the Parent windows children. This list shows the Child Window handle (HWND), The child window Class Name, whether the child window is visible or not and whether the child window is enabled or not.


Show

If the parent window is not visible this button will attempt to show it.


Messages

This button will open a messages window for the selected child window.


Hide

This button will attempt to hide the parent window.


VB View

This button will be enabled if this is a Visual Basic® form. Clicking will display the the Visual Basic  layout of the window.


Window Messages

This window displays all the messages sent to a window. It displays the message, the values of the wParam and the value of the lParam. If the lParam can be dereferenced in some way, i.e as a string, then the value of the string will also be displayed.

The caption of the window has the Handle of the window whoses messages are being intercepted and its caption.

The following Menu selections are available.

File

Exit.

Closes this message window and stops intercepting the window messages.

Options

Always Top.

Keeps this message window visible at all times.

Filter

Opens a filter dialog where certain classes of windows messages can be excluded from the display.

Edit

Cut

Cuts the selected messages to the Clipboard.

Copy

Copys the selected messages to the Clipboard.

Clear

Deletes all entryies from the messages display.

Output

Trace Window.

Sends the messages to be displayed on the Trace window. Messages will no longer be displayed on this window. Messages will continue to be sent to the trace window until this window is closed.

Message Window

Messages are displayed on this window.

File

Not yet implemented


WINTRACE.INI

This file must reside in the WINDOWS directory. It currently has the following sections.

[WINHELP]

The full path and name of the Windows™ SDK Help file.

[TRACE]

The Font and Font size used by the Trace Output Window are determined by the entries found here.

[RESOURCE]

The Font and Font size used by the allocated resources window are determined by the entries found here.

[IFLOADED]

This section lists the Tasks and Modules that can be selected for tracing etc. On an If Loaded basis. See the Debug Windowfor details.

[VALIDTYPES]

This section lists all the parameter types that wintrace recognizes. A typical entry is as follows:

HGLOBAL=size=2,format=%4X,validate=ProcValidateGlobal,Trace=ProcTraceGlobal

HGLOBAL:	The name of the parameter. This is the text that may be used in WINTRACE.APIfor IN=, OUT=, HT= and FT=. You may add your own types to this list.

SIZE:	This specifies how many bytes the parameters uses when it is pushed onto the stack.
 Note pushing a character actually pushes 2 bytes.

FORMAT:	This specifies a format string that can be passed to printf. It is used by the trace window to display the parameters.

VALIDATE:	This specifies the name of a function that will be invoked to validate the value of the parameter if you chooses the validate parameters option from the debug window. You may substitute your own functions in place of those used by Wintrace. Documentation and examples are shipped upon registration of wintrace.

TRACE:	This specifies the name of a function that will be called by the trace routines before the function has been called and after it has been called. You can use this to override and extend the default processing.
For example the call to GetWindowText passes a pointer to a buffer to receive the text. You can write a function that would display that text upon return from the call.

Documentation and examples of how to do this are shipped upon registration of wintrace.

[VALIDFUNCTIONS]

For a certain number of functions merely validating each  parameter one by one  is not enough to detect an error, in these cases you must validate all parameters at once. The entries in this section lists those functions and detail how to process them.

You can add your own functions here or modify the existing ones. Documentation and samples of how to do this are shipped upon registration.

A typical entry is as follows:

AddAtom=validate=ProcValidateAddAtom,trace=proctraceaddatom

AddAtom:	This specifies the name of the Function.

Validate:	This specifies the name of the procedure you wish to call to validate parameters that are passed to the function.

Trace:	This specifies the name of a procedure you wish to be invoked in lieu of the default trace procedure. The function will be called before and after the function is invoked.


WINTRACE.API

This file holds the list of APIs that are eligible for tracing,validating etc. An entry has the following format :

DLL=KRNL386.EXE;FUNCTION=LOCALALLOC;IN=X,X;OUT=HLOCAL;HT=HLOCAL

DLL=

this is the name of the module in which the function resides. This is the file name as it appears if you execute a DIR command, it is not the internal module name. Wintrace expects that this file is either currently loaded in memory or that it can be found in the path. If you add your own DLLs etc. to this list you must ensure that they are either loaded or that they can be found in the path before trying to use them with wintrace.

FUNCTION=

This specifies the name of the function in the module. This function must be EXPORTED in order for it to be used with Wintrace. If the function is exported by ordinal only then you can replace the FUNCTION= entry with :

ORDINAL=nn,FUNCTION=xxxxxxxx

Wintrace will use the text of the FUNCTION= in any display.

Both the FUNCTION= and ORDINAL= anticipate a PASCAL type calling convention. If the function you are interested in uses the C calling convention then use CFUNCTION= or CORDINAL instead.

If you are unsure of the ordinal number of exported functions use the popup menuon Wintraces opening display

IN=

This entry specifies the Parameters that are passed to the function. Wintrace uses this information for both tracing and parameter validation. The types that you can use must be selected from the list in the [validtypes] section of WINTRACE.INI. It is important to list all the parameters passed to the function and to ensure that they are of the correct type. If you are not interested in the value of the parameters passed to a function then you may omit this entry.

OUT=

This entry specifies the return type from the function. The valid types are listed in the [validtypes] section of WINTRACE.INI.

HT=

This entry indicates that the function allocates a resource that can be monitored via the monitor allocated resources option on the Debug window. The handle type must be one of those listed in the [validtypes] section of WINTRACE.INI.

FT=

This entry indicates that the function frees a resource. The FT= and HT= are mutually exclusive and should not be combined on the same entry. The type here should be the same as the entry for HT= on the API that allocated the resource

Wintrace ships with a WINTRACE.INI that contains the most commonly used APIs. In addition the following additional files are shipped:

SQL.API	A List of SQL Server DBLIB Calls

COMMON.API	A List of APIs that dont do much

TOOLHELP.API	A List of the TOOLHELP APIs

COMMDLG.API	A List of the Common Dialog APIs

MMSYSTEM.API	A List of the Multi Media APIs

VER.API	A List of the Version APIs

UNDOC.API	A List of Undocumented APIs


Allocated Resource
Allocated Resources

This window displays the list of resources that are currently in use by the monitored applications. It is opened in response to selecting the monitor resource usage checkbox in the debug window dialog. You can use this display to periodically see how your application is allocating and freeing resources.

Along with the type of resource and which module/Task allocated the resource Wintrace can also, in certain circumstances, determine the source file and the line numbers of  the code that made the call.

In order for Wintrace to do this the DLL or EXE that made the call must have embedded CodeView ™  debug information.

A typical display shows the following:

LOCALALLOC   called from line 25 of  VB2.C   Module VB2  Task  MEMGET HANDLE 1D0 Type HLOCAL Size 16

This shows that Module VB2 allocated a block of Local Memory that was sixteen bytes long. The allocation was made while task MEMGET was active. In this case Wintrace can determine that the call was made from line 25 of the source file VB2.C

For Memory allocations double clicking on an entry will display the contents of the memory area; Wintrace can only do this if the memory is locked.

APIs that allocate or free resources are designated using a HT= and a FT= entry in the WINTRACE.API  File. Wintrace keeps a list of resources that have not been freed by a call to an API with the associated FT= entry.

E.g. a call to LocalAlloc allocates a resource with a HT type of HLOCAL. Wintrace will consider this an outstanding resource until a corresponding call to LocalFree, which has a FT type of HLOCAL, is made.

The allocated resource display is not updated dynamically. You must use the Options, Refresh to get a list of the outstanding resources.

The other menu options available are :

Font:

Opens a dialog where you may chose the font for the display.

Sort:

Allows you to display the entries in the following order:

By Module:	Displays the list ordered by Module.

By Task:	Displays the list ordered by Task.

By Handle Type:	Displays the list ordered by the type of resource allocated.

By API:	Displays the list in Function name order.

Show Source

Opens a source window in which the source file that made the allocation will be displayed. The line of code that allocated the resource will be hilighted in red.

Count

This will open a dialog where a count will be displayed of the number of times each API selected in the Debug Window dialog has been called since tracing began.


Exceptions Window

If you have selected either of the check memory overwrites or parameter validation options in the debug window and Wintrace detects an error then the currently executing task will be suspended and the Wintrace exception window will be displayed.

While the exception window is open no other task will execute. CTRL-ESC and ALT-TAB will not function. Wintrace uses the LockInput( ) function to achieve this.

The exception window compromises three MDI Children with the following information:

Error Window

This window displays why the exception was triggered. This will be either a parameter error or a memory block has been overwritten. In the case of a memory error the error text will inform you of which handle has been overwritten and where the handle was allocated from. If the module in question has CodeView ™  embedded debug information Wintrace will also display the source file and the line in it where the memory was allocated.
For a Parameter error Wintrace will display the function name the DLL it was called from the value of the invalid parameter and its type. It will also display the name of the module that made the call and the offset within it. If the module in question has CodeView ™ embedded debug information Wintrace will also display the source file and the line in it from where the call was made.

Stack Window

The stack window will show the call history up to the point that the exception occurred. The most recent entry will be shown first. Wintrace will show the name of the module and the offset within it that the call was made. If the module in question has CodeView ™ embedded debug information Wintrace will also display the source file and the line in it from where the call was made.

Source Window

If the module in question has CodeView ™ embedded debug information Wintrace will also display the source file in this window and will hilight, in red, the line of code that caused the exception or that allocated the block of memory.

The following options are available from the exceptions window menu:

Terminate:	Terminate the task that caused the exception

Continue:	Allow the task to continue executing. Depending on the nature of the exception your

machine may shortly become unstable.

How it Works.

Memory Overwrites.

Each time a LocalAlloc( ) or GlobalAlloc( ) is invoked Wintrace increases the requested allocation by one byte. If the request was successful it places a S in this extra byte. Every time Wintrace gets control, via an API INT 03 Hook, It scans through any currently allocated memory blocks checking for the S. If one isnt found it triggers an exception.

If your Program has been compiled with debug information then Wintrace will trap overwrites of memory by the C runtime functions such as strcpy and strcat etc. It will also trap overwrites of  both Global and Local  C variables. i.e.

char MyArray[5];

main( )

{

strcpy(MyArray,12345678);

}

This would be trapped.

NOTE:  You activate the trapping of these runtime functions by expanding the [_RUNTIME] section on the debug Window and selecting the relevant functions or by expanding the [_RUNTIME] section and using the mark imports button.

THIS FEATURE  WILL ONLY WORK WITH PROGRAMS COMPILED WITH THE LARGE MODEL. DO NOT ATTEMPT TO MONITOR RUNTIME FUNCTIONS WITH ANY OTHER MEMORY MODEL.

Parameter Validation.

At the entry point of each selected API Wintrace writes an INT 03 instruction. It then installs its own INT 03 Handler. Every time the INT 03 Handler is invoked Wintrace calls the relevant tracing and parameter validation routines depending on the debug selections that you made. It then restores the Code and places another INT 03 at the return address so that it can trap the returns.

Extending Wintrace.

Wintrace can be extended by adding new parameter types,  new DLLs and functions to be monitored. You can also write your own trace and validation routines that replace the default routines shipped with the product. Documentation and examples of how to do this are shipped upon registration.


Executeable Resources
Executable Resources

This window displays a list of the resources that are embedded within the selected .EXE or .DLL. Double Clicking on an entry will open a window where the resource will be displayed in a manner suitable for its type.


First Meg of Memory

The following display, activated by selecting either the below 1MB button or the view below 1MB menu option from the main dialog, displays a list of modules and tasks that have allocated memory with a linear address of less than 1MB.

Memory below 1MB is required in order for Windows™ to start a new task. If there is not enough memory available the message Insufficient memory to start a new application.... will be displayed.

Double clicking on an entry will show the detailed memory usage for the selection.


Summar Line
Summary Line

Displays the total amount of memory available below 1MB, the Total number of bytes free below 1MB and the total number of bytes below 1MB are marked as discardable.


Usage Summary

Displays a module name, whether the memory used is associated with the task or the module and the total number of bytes below 1MB used. Double Click for a detailed break down.


Detailed Usage

Displays details about each Global Handle that is allocated below 1MB. The detail line includes: Handle, Size, Type (Code, Stack etc.), and whether the memory is discardable or not.


GPF Handler

When you start wintrace it automatically installs a GPF Handler. Whenever a GPF occurs Wintrace will be activated. It will display the type of GPF that occurred, the task and module that the GPF occurred in and a stack trace.

If the module that the GPF occurred in has Codeview™ information it will also display the line number that the GPF occurred at.

The only safe option to use from the available menu option is terminate task.


VXD List

This screen, displayed by selecting VXD List from the main menu, displays a list of all the VXDs loaded in the system. The screen lists the name of the VXDs.

Double click on any entry for a detailed display.


VXD List

The list of VXDs loaded. Double click on an entry for more detail.


VXD Help

Click this button for help.


VXD Detail

This screen is displayed by double clicking on an entry on the VXD List display


VXD ID

The ID, in hex of the VXD. This number can be used with the INT 2F 1684H call to get API entry addresses.


Major Version

The Major version number for this VXD


Minor Version

The Minor version number of  the VXD.


Initialization order

The initialization order for this VXD. A value of 80000000 indicates no particular order.


Control Proc

This displays the 32 bit offset of the VXDs control procedure. This entry address is used by the system to notify the VXD of interesting events occurring within the system.


V86 API

This displays the 32 bit offset of the VXDs V86 API entry point. If this field has a value then it is possible to call this VXD from a DOS Box. Use the INT 2F 1684H call with BX set equal to the device ID. The entry point will be return in ES:DI.

This is not much use unless you know the format of the API calls


PM API

This displays the 32 bit offset of the VXDs Protected mode API entry point. If this field has a value then it is possible to call this VXD from a protected mode application, usually a windows application. Use the INT 2F 1684H call with BX set equal to the device ID. The entry point will be return in ES:DI.

This is not much use unless you know the format of the API calls


Number of Services

This shows a count of the number of services this VXD provides for other VXDs to call.


Common Bugs
Common Reasons For Failures

This area lists some of the more common reasons why things break.

Low Memory.

Most people assume that with Windows 3.1 it was no longer necessary to worry about conventional DOS memory. Windows would simply use your hard drive to create virtual memory and you could basically do what you want. Unfortunately this is not true. When Windows starts a new task it requires 512 bytes of conventional memory to create what is called the task database. If Windows cannot find 512 bytes of conventional memory you will get the insufficient memory - close one or more applications message.

Use the Below 1MB option to find out who is grabbing all of your conventional memory. If it is applications you have control over replace any GlobalAlloc(GPTR,nnnn) with GlobalAllocPtr(GHND,nnnn). Also take a look at your .DEF and .RC  files and make sure that everything is defined as DISCARDABLE and MOVEABLE.

Protected Mode

There is a wide spread belief that because Windows ri\uns in enhanced mode that it is impossible for one application to do something that would cause another application to break. Unfortunately this is not true. Windows does indeed run in protected mode and any attempt Within a VM to access anothers VMs address space will cause a protection exception. The problem is that all your windows applications run in the same VM thus they can all access the same memory addresses and basically do whatever they want. I.e there is nothing within Windows that will prevent an errant application from freeing your memory or even overwrting it.

Resources.

All resources are equally important but some are more important than others. For instance if your applications does several GetDC calls without a corresponding ReleaseDC call your system will eventually freeze.

Use the Monitor resources option from the debug window and check the allocated resources window for this kind of problem.

Global Memory.

When you allocate a block of Global Memory Windows usually allocates more bytes than you asked for. This can cause you to inadvertantly overwrite memory without causing a GPF. The only safe way to catch this is to use the  check for memory overwrites  from the debug window.


Visual Basic Window

This window is displayed by pressing the Visual Basic View button the Windows Detail screen.

This screen displays the visual basic controls on the form. Clicking on a control will populate the propertys and events windows for that control. You can traceVB Events for a control by selecting the events from the Events window and clicking the trace button. This will open the trace window where trace information will be displayed.

The information displayed will be the Task Name, The control name, The event and the values of the parameters at entry to the function.


VB Controls

A list of all the Controls on a form, including the form.


Control Properties

A list of  ALL the properties of the selected control and their current values.


Control Events

A list of the events for the selected controls and the parameters passed.


VB Trace

Clicking this button opens the Trace window and begins tracing of the selected events for the selected control.